home *** CD-ROM | disk | FTP | other *** search
/ Gigarom 4 / Mac Giga-ROM 4.0 - 1993.toast / FILES / UTI / E-H / HeaderFKEY 1.0a7.cpt / HdrKey 1.0a7 Read Me next >
Text File  |  1990-12-04  |  9KB  |  231 lines
  1. /*
  2. -----------------------------------------------------------------------------
  3.  
  4.             HeaderKey    v1.0a7    12/03/90
  5.             
  6.             Copyright 1990 Brian Fitzgerald
  7.             All rights reserved.
  8.  
  9. -----------------------------------------------------------------------------
  10.  
  11.     About HeaderKey
  12.     ---------------
  13.  
  14. I got tired of making function header comments by hand, so I tried to
  15. write one using the MPW shell commands. After everything was said and
  16. done, the script took over 20 seconds to execute! Ridiculous. So I
  17. started to make a real MPW tool that did this, then said "Waitaminut!
  18. Why not make it an FKEY?
  19.  
  20. Why not? So, after a long Sunday afternoon, and a week of fixes,
  21. we have HeaderKey 1.0a7.
  22.  
  23. This is an FKEY (id=9) that will bring up a dialog allowing you to
  24. enter information about the function, and choose a language to spit out
  25. that information in a comment header. You have to PASTE after you run
  26. the FKEY to get the information into your text editor.
  27.  
  28.  
  29.     Very preliminary
  30.     -----------------
  31.  
  32. However, this is a very preliminary version. It only supports C and
  33. assembly (I made it for assembly-language programming, but in the process
  34. of debugging it added the C support (it's written in Think C) ). It has a
  35. few quirks. It's somewhat rigid (inflexible). But it's still darn useful.
  36.  
  37. New as of version 1.0a7 - cmd-U to update the display of the header so
  38. you can see what it will look like. Also, cut/copy/paste work (they did
  39. in 1.0a2 but probably no one tried it!). And finally, added some hacks so
  40. that the desk scrap will copy back and forth correctly.
  41.  
  42.  
  43.     What do I do?
  44.     -------------
  45.  
  46. OK, the Header FKEY file has 4 DLOG resources, 4 DITL resources, and
  47. an FKEY resource. If you have Suitcase or some such, then great - just
  48. open the file up, and you're going. If not, then you need to paste
  49. these resources into your System file. Since this FKEY is really
  50. intended for programmers, I hope you know how to do that. No? Well,
  51. quick instructions (you of COURSE have a backup and you KNOW that I
  52. can't be held liable etc). From Finder (not MultiFinder), double-click
  53. on the "Header FKEY" file to open ResEdit. Also open the System file
  54. from the system folder. Copy DLOG from "Header FKEY". Paste into
  55. "System". Repeat with DITL and FKEY. Close System (save changes). Quit.
  56. Ok, you got it.
  57.  
  58. To use it, just run your favorite programming editor (Think C, MPW,
  59. or whatever). Hit command-shift-9. You should see a dialog box
  60. (since this is a TEXT file, sorry no pictures). Fill in the three
  61. boxes, click on the appropriate language button (C or Asm only for now,
  62. sorry!), then click the "Make Header" button. Now, do a PASTE (this
  63. is always command-V). You should see your header appear in all it's
  64. glory. (If not, and you are using Think C, see below).
  65.  
  66.  
  67.     Known bugs and quirks.
  68.     ----------------------
  69.  
  70. 1.    none
  71.  
  72.     There is one thing- the handling of the desk scrap. Since an FKEY
  73.     invocation doesn't trigger window activate/deactivate events, most
  74.     applications don't write their private scrap to the desk scrap. MPW
  75.     knows that the desk scrap changed when the FKEY exited, Think C sometimes
  76.     doesn't (if you COPY'd, then ran the FKEY, you would not get your
  77.     crafted header pasted in).
  78.     
  79.     To fix this, I added some code hinted at by Mike Livewright. If the
  80.     TE scrap has something in it, copy it to the desk scrap on entry, and
  81.     copy the desk scrap to the TE scrap on exit. This kinda bothers me, but
  82.     it seems to work for Think C. Unfortunately, it doesn't work for the
  83.     MPW editor. A little poking about with The Debugger (triggering on
  84.     Scrap Manager traps) reveals that Think C uses the TE scrap (even though
  85.     they have their "PE" replacement for TextEdit, it evidently shares some
  86.     of the globals et al. But MPW is a more robust editor, and has entirely
  87.     private data structures, ones I didn't feel like busting into. So if
  88.     I get the MPW part working, I'll have to give up the TE scrap copy idea,
  89.     or recognize which editor was active on FKEY invocation (ugg!).
  90.     
  91.     So, Think C should work just fine, but in order to IMPORT a scrap into
  92.     the FKEY (which isn't supported yet anyway), you need to COPY, then
  93.     change windows to force the private MPW scrap into the desk scrap.
  94.     The copying via the desk scrap on exit from the FKEY seems to work just
  95.     fine the way it is, however, and that's the important part (for now).
  96.  
  97.  
  98.     Where am I going?
  99.     -----------------
  100.     
  101. Near-term future plans
  102.  
  103.     o    Finish up Pascal support.
  104.     o    Add flourishes to C and Asm support.
  105.     o    Allow defaults to be "sticky" from invocation to invocation.
  106.     o    Allow defaults to be saved to disk.
  107.     o    Fix known bugs.
  108.     o    Add better help.
  109.  
  110. Long-term plans
  111.  
  112.     o    Add template parsing to add flexibility to comment generation.
  113.     o    Read scrap on FKEY start to generate defaults for fields.
  114.     o    Make "sets" for ease of generating multiple comment formats.
  115.  
  116. Let me know how useful (or useless) this FKEY is. I am willing to
  117. entertain most reasonable requests for formats, languages and so forth.
  118. I wrote this for myself and a few others, and would like to widen the
  119. circle. Programming tools are so primitive! Let's get some better ones
  120. out there. (Not that this in itself should be construed as a "better one").
  121.  
  122.  
  123.     Reporting bugs
  124.     --------------
  125.  
  126. I am releasing a preliminary version because
  127.     1) I think this is so neat that people need this know.
  128.     2) I'd like to find out about bugs.
  129.  
  130. To reward bug reporting, I will give free registrations as follows
  131.  
  132.     1.    You are the first to report the bug. (I may have already fixed it!)
  133.     2.    It has to be reproducible (ie I have to see it myself).
  134.     3.    Not insignificant (cosmetic problems are not bugs, but I
  135.         would like to hear about them).
  136.  
  137. I will be fairly liberal with registrations. This policy will be in
  138. effect until further notice or until I go broke from free registrations.
  139.  
  140.  
  141.     Shareware
  142.     ---------
  143.  
  144. Ah yes, that plea. You've heard it all before. Here are the terms - you
  145. can evaluate for 10 days (if you know if you need this after 10 days of
  146. evaluation, then trust me you probably do but just don't realize it).
  147. After that, please stop using, or register it.
  148.  
  149.      $5.00        You want to register it, and get on mailing list
  150.     $10.00        You want to register, and also get the next 2 upgrades free.
  151.     $20.00        Register, 2 upgrades, and source code.
  152.     
  153. You can pay check or cash. If you are foreign, and have problems with
  154. check transfers (ie large bank charges), send me an e-mail or US mail and
  155. I might be able to work out a credit card transfer through a local computer
  156. store.
  157.  
  158. If you got this package, there should be two files
  159.  
  160.     Header FKEY v1.0a7
  161.     HeaderKey v1.0a7 readme
  162.  
  163. If you are passing this on, you must distribute both files together.
  164. Please. As long as both files are passed together, put it anywhere you
  165. can.
  166.  
  167.  
  168.     Where to write
  169.     --------------
  170.  
  171. Brian Fitzgerald
  172. 18942 Dallas Ave
  173. Riverside, CA 92508
  174. USA
  175.  
  176. CompuServe:        72250,3226
  177. GEnie:            HAL.LABS
  178. BIX:            bfitz
  179. AppleLink:        D0366
  180. Ma Bell:        (714) 780-3328        only between 6PM and 12PM
  181.  
  182. December 3rd, 1990
  183.  
  184. ps - if you get this more than 1 year after the above date, don't assume that
  185. the address and phone number are still good. However, my electronic IDs will
  186. probably be good for longer than the life of the Macintosh.
  187.  
  188.  
  189.  
  190.     Change History
  191.     --------------
  192.  
  193.     12/03/90    1.0a7    Now show the scrap as it is being built. The user
  194.                         can hit cmd-U to update the display (rebuilding
  195.                         is slow right now, so this is not done automatically
  196.                         yet..). Fixed all known bugs. Second release.
  197.                         Added hooks for using tabs or spaces (could be an
  198.                         option later, but it was added for the clipboard
  199.                         display). Added kludge for Think C editor.
  200.     
  201.     12/01/90    1.0a6    Reworked header forming code to take parameters.
  202.                         The "open/close" buttons are respected to slightly
  203.                         modify the formed header, and the margins are
  204.                         respected.
  205.     
  206.     11/29/90    1.0a5    Added new dialog to customize spacing parameters.
  207.                         Set up for read/write of parameters to disk, but
  208.                         left for future implementation.
  209.     
  210.     11/28/90    1.0a4    Changed it to use global variables (from A4) to
  211.                         make modularization easier (some routines need
  212.                         global variables). Moved constants and prototypes
  213.                         into header file. More fix to update problem.
  214.  
  215.     11/26/90    1.0a3    Fixed updating problems. Also fix spaces in front
  216.                         of lines, and blank lines to form separators. Add
  217.                         tweaks so that we have a start/end char. Need to
  218.                         rework all this so it's cleaner. Added cut/copy/
  219.                         paste support to main dialog.
  220.  
  221.     11/26/90    1.0a2    Added assembly language headers, changed to 72
  222.                         column lines. Fixed at 0/12/68/72, but need to
  223.                         add dialog so that users can edit this to their
  224.                         preferences. Lots of choices unfortunately.
  225.  
  226.     11/25/90    1.0a1    First version. Choose between C, Asm, and Pascal
  227.                         Headers. Put header in system scrap for pasting into
  228.                         any editor. Only supports C, with fixes needed as
  229.                         indicated below.
  230.  
  231. */